﻿/** Pete's Tools package */
package pete.tools
{
	/**
	 * @version
	 * 0.1
	 *
	 * @description 
	 * A set of static functions to include randomness.
	 */
	 
	public class Random
	{
		/**
		 * Returns a random <code>Boolean</code>, based on the given value. A higher value will return <code>true</code> more often than not.
		 * 
		 * @param percentage The value to test randomness. The range is 0-1.
		 *
		 * @return Boolean
		 *
		 * @example
		 * <pre>
		 * if (Random.chance (.15))
		 * {
		 * 		// Do something
		 * }
		 * </pre>
		 */
		public static function chance (percentage:Number = .5):Boolean
		{
			var random:Number = Math.random ();
			
			if (random < percentage)
			{
				return true;
			}
			else
			{
				return false;
			}
		}
		
		/**
		 * Returns a random <code>IntegerBoolean</code>, based on the given range.
		 * 
		 * @param beginIndex The lowest number in the range.
		 * @param endIndex The highest number in the range.
		 *
		 * @return Integer
		 *
		 * @example
		 * <pre>
		 * var test:int = Random.choose (0, 3);
		 * trace (test); // Could be 0, 1, 2, or 3
		 * <br />
		 * var test2:int = Random.choose (-2, 2);
		 * trace (test2); // Could be -2, -1, 0, 1, or 2
		 * </pre>
		 */
		public static function choose (beginIndex:int, endIndex:int):int
		{
			var option:int = beginIndex + Math.round (Math.random () * (endIndex - beginIndex));
			
			return option;
		}
		
		public static function chooseItemFrom($array:Array):* {
			
			var i:int = Random.choose(0, $array.length-1);
			
			return $array[i];
		}
		
	}
}
		